COMMENT ⊗   VALID 00009 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002	SPOOLER SYSTEM DOCUMENTATION:
C00005 00003	SPOOL & XSPOOL Create Spooler Commands.
C00011 00004	Delayed listings, Page range selection, Repeat copies
C00014 00005	XSPOOL Special Features
C00017 00006	QSPOOL
C00019 00007	UNSPOOL	
C00022 00008			The Spooler
C00026 00009			Spooler Version 2 Operating instructions.
C00029 ENDMK
C⊗;
SPOOLER SYSTEM DOCUMENTATION:
	SPOOL, QSPOOL and UNSPOOL, [LIST] and [xSPL]

		Spooler for line printer listings

			R. E. Gorin 15 Feb 1971
			Revision #6.  25 April 1973

	Spooling provides a method of producing line printer listings
of files without the usual disadvantage of tying up a users job while
the listing is actually being done.

	To use the spooler,   a user must create commands for  it.  A
command  is  the  name  of a  file  to  list,  and control  switches.
Spooler commands are created by the system command "SPOOL." 


	This file documents the entire spooler system:
	SPOOL	- Accept commands to spool files to the LPT.
	XSPOOL	- Accept commands to spool files to the XGP.
	[LIST]	- The actual LPT listing program.
	[XSPL]	- The actual XGP listing program.
	QSPOOL	- Spooler status report program
	UNSPOOL	- Deletes spooled requests. Modifies PRINTR behavior
	SPSUB	- Subroutines to make spooler command files
		  (These subroutines are documented separately in
		  SPSUB.REG[UP,DOC].)



	Example of Spooling.

The monitor level command:

SPOOL SPOOL.REG[UP,DOC]

will cause  the  LPT spooler  to list  this file,  SPOOL.REG[UP,DOC].
When the  listing is completed,  the  requestor will be notified with
a message on his terminal.

	Spooled listings are  preceeded by a title  page  (except see
/NOTITLE  below),  used   to  make  it  easy  to  separate  different
listings. This title  includes the  file identifier, the name of  the
requestor, and his  project- programmer number, the  current date and
time,  and  the  date  abd  time  when  the  file  was last  written.
Programmer names are read  from the file FACT.TXT[SPL,SYS].   Project
names   (of  which   there   are  few)   are  read   from   the  file
XFACT.TXT[SPL,SYS].
SPOOL & XSPOOL Create Spooler Commands.

	In the discussion below,  'SPOOL' is used to mean  either the
command  'SPOOL' or the command  'XSPOOL', except as  noted.  'SPOOL'
makes requests for the LPT  spooler; 'XSPOOL' makes requests for  the
XGP spooler.

	To  have  the  spooler  make a listing the user must tell the
spooler what file(s) to print.  This easiest way to tell the  spooler
what  to  do  is  by  the  system  level  command SPOOL. This command
consists of the word SPOOL followed by the name(s) of the file(s)  to
be  listed.   File names are separated by commas.  Each file name may
be followed by switches, explained below.   The  program  Spool  will
send  commands  to the spooler.

	Files to be spooled are specified in the conventional way, by
file name, extension, and optionally project-programmer number.

	Asterisk, *, may be used to allow matching  of any file name,
extension, project name or programmer name.  (RPG, DMP and REL files
will not be matched by * in the extension).

	Switches are allowed  either preceding or following  the file
name.  Switches  that precede the name are sticky and will be applied
to subsequent names. A switch  consists of a slash, the switch  name,
and sometimes, a parameter. For example, /REPEAT=5.

	The  following  switches  are  available.    Note  that  most
switches occur  in two senses ('delete'  and 'nodelete'). This allows
an explicit switch in some term to over-ride a sticky switch.

Switch		Action.

DELETE		DELETE this file after printing. The file  protection
 NODELETE	of  this file  must be low enough so that the spooler
		can delete it. 	The file must belong to the requestor
		(Alias not allowed).

NONUMBER	Omit SOS  line numbers  from the  listing. 'N' is an
 NUMBER		accepted abbreviation for 'NONUMBER'.

FORTRAN		The first character  of each  line is interpeted as a
 NOFORTRAN	Fortran carriage control character.

LPT100		The spooler will open the LPT in mode 100, instead of
 LPT0		mode 0.

HEADING		Print a page heading at the top of each page. 'H'  is
 NOHEADING	accepted as 'HEADING'.   HEADING  is  implied for all 
		files, except: 
			"LST" or "DOC" extensions,
			any file from any area with programmer = DOC.
		The heading includes date, time, file name  and  page
		numbers. 

TITLE		Precede the listing with a title page.  'TITLE' is 
 NOTITLE	implied for all files.

NARROW		Center the title page to fit an 8.5 inch wide page.
 NONARROW

RECOPY		Copy the file to  [SPL,SYS]  and list the copy.  This
 NOCOPY		allows  the file to be edited while the listing is in
		progress.

REPEAT=n	Make n copies of the listing. (REPEAT is NOT sticky).

EXTRA=n		Insert n extra line feeds in the listing  after every
		line feed in the file. (EXTRA is NOT sticky).

DUMP		Octal listing.  Data will be printed  as  octal  full
 NODUMP		words. ('OCTAL' is an equivalent switch.)

NOFF		Each line feed in the file is translated to  '177&'21
 FF		which causes single spacing with no form-feed between
		pages.

NOWARN		Suppress  "spooling done" message when listing is done.
 WARN

ASK		Before making the spool command, SPOOL will  type  the
		file name and wait for the user to respond with "Y" to
		spool the file. (This is useful with *.* terms).

HOLD=hhmm	The listing will be held in the queue  until  the  time
		specified by hh hours, mm minutes. (24 - hour  time  is
		assumed.)  If hhmm is prior to the current time,   hhmm
		tomorrow is assumed.

MODE=n		Open the file in mode 'n' ('n' is octal).

Delayed listings, Page range selection, Repeat copies


DELAYED LISTING

	Usually requests for spooled listings will  be  processed  as
rapidly  as  possible.   Under  some  circumstances  this  may not be
desired.  For example, a long listing impacts the normal operation of
the  system  by  making  the  line  printer  unavailable  during  its
duration.  The spooler allows users to delay such  listings  until  a
time  of  minimum loading (e.g., 0500) when the unavailability of the
line printer is less likely to interfere with other users.

	If  the construction  /HOLD=hhmm appears  in  a command  line
then  hhmm is  interpreted  as the  (24 hour)  time  of day  when the
listing should actually be sent  to the line printer. In the  example
below, 1730 will be interpreted as 5:30 PM.

Example:	SPOOL SYSTEM.LST[S,SYS]/HOLD=1730

	If the time specified is smaller than the current time, it is
interpreted  to mean, "list the file tomorrow at the time specified".
That is, if at 10PM you give the command:
		SPOOL BAZ.FAI/HOLD=400
then the listing will occur in six hours.


PAGE SELECTION

	You may follow a file name by a list of ranges of pages  that
you want listed. The list must be parenthesized. For example:
		SPOOL FOO.SAI (1,7,5:8)
will  cause  page  1,  page  7  and pages 5 through 8 inclusive to be
listed. Page ranges are never sticky.

	In octal dump mode, this page range list is used  to  specify
a word-range to list.

		MULTIPLE COPIES OF A FILE

	The REPEAT  switch  (/REPEAT=n) is  accepted by  SPOOL.   The
effect is  to interpret n as  a decimal number and  to list that many
copies of  the file.  Multiple copies  are spooled  as usual,  except
that the  two pages of heading  that normally precede a  file (except
if  the /NOTITLE  switch is  used) are  suppressed on the  second and
subsequent copies of the file.
XSPOOL Special Features

	The XSPOOL  command is  quite similar  to the SPOOL  command.
The  XGP  has greater  flexibility  than the  line  printer,  so more
parameters can be specified in the XSPOOL command.

	The following switches are legal only in the XSPOOL command:

FONT#n=f	'n' is a number from 0 to 15 decimal.  'f' is a file
		name.   The  XGP spooler will use the font named 'f'
		as font 'n' when spooling.  If '#n' is omitted,  n=0
		is assumed.    Up  to  16  font select switches  are
		permitted.

LMAR=n		Set left margin to column 'n'.    Columns in the XGP
		are numbered from  0  to  1699 (approximately).  The
		left margin  is the column which the carriage return
		character selects.

RMAR=n		Set right margin to column 'n'.   If the XGP is going
		to write a character that exceeds this margin,  a new
		line will be started.

TMAR=n		Set  the  number  of blank scan lines between the top
		edge of the page and the first line of text.

BMAR=n		Set the number of blank scan lines between the bottom
		of the text and the bottom edge of the paper.    (The 
		system interprets BMAR=0 to mean no paper cutting.)

PMAR=n		Set the number of scan lines in the page body.   Text
		is written inside this area.

XLINE=n		Set the minimum interline spacing to  'n'  scan lines.

	More pecularities:
;***** the following is not yet implimented in full: (5/9/73)
	If any explicit FONT selects are made  in the XSPOOL command,
no /TITLE switch  will be assumed, unless it is explicit.  Similarly,
if any FONT select  switch specifies some  font number other than  0,
no /HEADING switch will be assumed, unless it is explicit.

	Page headings  will occur  in font#0.   Whatever font  was in
effect  before the heading line will  be reinvoked before any further
processing. The title page, if present, will be made in font#0.
QSPOOL

	The QSPOOL  command  starts the  SPOOL program  in a  special
way.  QSPOOL  reads the  directory  of [SPL,SYS]  and  interprets the
contents of the  SPX and XSP (spooler  command) files.   Essentially,
it displays the queue of files to be printed.

	The queue is based on a priority scheme.  The priority  of  a
spool request is determined by
  <time in minutes since spool request, +1>/<file size in records>

	Requests are processed in the order of decreasing priority.

	Line printer allocation:

	The spooler uses  the following scheme  when it wants  to use
the line  printer.  It uses  the DEVUSE uuo to  determine if there is
any one in  the queue waiting  for the LPT,  and if  there is such  a
person, it waits until there is no  one waiting for the LPT and there
is  no  one using  the  LPT.   Once  the  LPT is  initialized  by the
spooler,  the  spooler hangs  on  to  it  until  either  it  finishes
processing all  command files,  or  it begins a new  listing file and
discovers that some  one is queued  waiting for the  LPT.  In  either
case, the spooler releases the LPT.
UNSPOOL	

	UNSPOOL  is  a monitor level command that invokes the program
SPOOL in a strange way:
	If  you  run UNSPOOL it will display all the spooler commands
that you (your PPN) have requested, and it will allow you  to  delete
any  of  the command files that it displays.  If you delete a command
file that hasn't been  seen  by  the  spooler  then  nothing  special
happens  since  the  spooler  is  not yet aware of the command, so it
won't be missed.     If  it  happens  that  the  spooler  is  already
processing your commands then the listing in progress will be purged.

	If  you  log  in as SPL,SYS and run Unspool then not only are
you allowed to purge any command file that is either in  progress  or
pending but you also can change the spooler behavior in the following
ways:
	1.  You can cause the present listing to be purged.
	2.  You can cause the present listing to be started over.
	3.  You can cause the spooler to hold the queue and release
	    the LPT immediately before starting the next file.
	4.  You can release the queue from the state induced by
	    holding it.
	5.  You can suspend spooling, breaking the listing that is
	    currently in progress and releasing the LPT. When you 
	    escape from this mode by using the release queue command,
	    the listing that was broken will be resumed.
		The Spooler

	The spooler, i.e. the program that actually lists user  files
is  called  [LIST]  and  runs logged in as [SPL,SYS].   The following
document is copied from the spooler internal documentation.    It  is
for  the  purpose  of  allowing other programmers to interface to the
spooler from their own programs without  going  through  the  program
SPOOL.  The  following  information  is  subject  to revision without
prior notice.

	Command  files  to the spooler are written in dump mode, mode
17 on the DSK.  The command file must be precisely 200 (octal)  words
long. Any name is allowed for the file name; the extension is SPX.

The file shall contain the following data:
	NAME	WORD NUMBER
SDEF	CFORM,	0		;CONTAINS THE FORMAT VERSION NUMBER.
SDEF	RQNAM,	1		;SIXBIT PPN OF REQUESTOR.
SDEF	RQJOB,	2		;LINE NUMBER,,JOB NUMBER OF REQUESTOR
SDEF	FDEV,	3		;SIXBIT NAME OF DEVICE (0 = DSK)
SDEF	DEVMOD,	4		;0,,SOURCE DEVICE MODE.
SDEF	FSIZE,	5		;FILE SIZE IN 200 WORD RECORDS IS PLACED HERE.
SDEF	RQTIME,	6		;DATE,,TIME IN MINUTES WHEN REQUEST WAS MADE
SDEF	FNAME,	7		;SIXBIT FILE NAME OF FILE TO BE LISTED
SDEF	FEXT,	10		;SIXBIT EXTENSION,,0
SDEF	FDAT,	11		;FILE DATE AND TIME ARE SAVED HERE
SDEF	FPPN,	12		;SIXBIT PPN OF FILE OWNER, (0 = RQNAM)
SDEF	ANAME,	13		;ALIAS NAME
SDEF	AEXT,	14		;ALIAS EXTENSION
SDEF	APPN,	15		;ALIAS PPN
SDEF	CBITS,	16		;LISTING CONTROL BITS
SDEF	CREP,	17		;REPCOUNT,,LINE EXPANSION COUNT
SDEF	PSPEC,	20		;PAGE SPECIFICATION LIST

FILE CONTROL FLAGS   CBITS RIGHT

SDEF	DELBIT,1		;DELETE
SDEF	FORBIT,2		;FORTRAN CONVERSION
SDEF	OMDBIT,4		;LPT MODE 100
SDEF	NONBIT,10		;NO NUMBERS
SDEF	PHDBIT,20		;PAGE HEADINGS
SDEF	NOLBIT,40		;NO LOGO
SDEF	NARBIT,100		;NARROW PAGE HEADINGS
SDEF	OCTBIT,200		;OCTAL DUMP
SDEF	QBIT,400		;QUIET. NO MESSAGE ABOUT SPOOLING DONE.
SDEF	LFBIT,1000		;SUBSTITUTE 177 21 FOR EVERY LINE FEED.


CREP/	LEFT SIDE:	FILE REPEAT COUNT
	RIGHT SIDE:	EXTRA LINE PARAMETER. (IF <0 THEN SET THE LFBIT)

PSPEC/
	IF ZERO, THEN SPOOL ENTIRE FILE.
	IF ZERO LEFT HALF THEN  RH,,RH
	LH = LOW PAGE, RH = HIGH PAGE IN PAGE RANGE TERMS.
	TERMS ARE PROCESSED UNTIL A ZERO TERM IS SEEN.

		Spooler Version 2 Operating instructions.


There are three programs pertaining to the spooler.

	[LIST]		The spooler.
	SPOOL		The command creation program
	SPOOLQ		The spooler queue interrogation program

[LIST]

	[LIST]  runs  as  a  detached  job,  logged  in under the ppn
SPL,SYS. The job is identified by the name  [LIST].   Normally,  when
idle the spooler will spend most of its time in INTW, interrupt wait.
When it is listing a file, it will  be  mostly  in  IOWQ  with  brief
excursions  into  RUNQ.  If the spooler goes into IOWQ and nothing is
listed, it may be sleeping,  waiting  for  the  line  printer,  which
someone else may have assigned.

	The spooler may crash, entering STOP status. If this happens,
chances are that it has grabbed the line printer, rendering  the  LPT
unavailable to all.  To remedy this, attach to the spooler's job  and
kill it.  The system will start a new spooler within one minute.

SPOOL

	SPOOL  is  used to create command files to the spooler. SPOOL
is kept on the system area. It is accessed either by R SPOOL,  or  by
the monitor level command SPOOL.

	When  SPOOL  starts  it does a NAMEIN to see if it can find a
program named [LIST].  If it can't find such a  program,  SPOOL  will
do a WAKEME uuo to initiate new spooler.

	SPOOL  creates  command  files  with  "SPX" extensions on the
spoolers disk area [SPL,SYS].  These files are read by  the  spooler,
and   they   contain  the  name  of  the  file  to  be  listed.